Reinstate supplemental remarks (various)#12709
Open
gewarren wants to merge 5 commits into
Open
Conversation
github-actions
Bot
added
the
area-Meta
Contributor
There was a problem hiding this comment.
Pull request overview
This PR reintegrates “supplemental API remarks” content back into this repo by replacing the external “Supplemental API remarks” links with inlined markdown remarks across several API reference XML files. It also adds new snippet projects/files to support the expanded remarks content (notably for System.Numerics and System.Collections.Generic).
Changes:
- Replaced “Supplemental API remarks” links with inlined
<remarks><format type="text/markdown">…</format></remarks>content across multiple XML API docs. - Added new C#, Visual Basic, and F# snippet projects and sources referenced from the restored remarks.
- Updated/expanded several API pages with longer conceptual guidance (security notes, algorithm explanations, usage patterns).
Reviewed changes
Copilot reviewed 45 out of 45 changed files in this pull request and generated 10 comments.
Show a summary per file
| File | Description |
|---|---|
| xml/System.Security/SecureString.xml | Restores detailed remarks (including guidance and security limitations). |
| xml/System.Security.Cryptography/RSAParameters.xml | Restores detailed RSAParameters conceptual remarks and field summary. |
| xml/System.Security.Cryptography/RSACryptoServiceProvider.xml | Restores remarks about CSP key sizes and CAPI interop behavior. |
| xml/System.Security.Cryptography.Xml/SignedXml.xml | Restores extensive XMLDSIG/SignedXml usage + security considerations. |
| xml/System.Numerics/Complex.xml | Restores extensive Complex overview remarks and adds snippet references. |
| xml/System.Numerics/BigInteger.xml | Restores extensive BigInteger overview remarks and adds snippet references. |
| xml/System.Net/HttpListener.xml | Restores HttpListener overview remarks including security guidance and HTTP.sys notes. |
| xml/System.Net/FtpWebRequest.xml | Updates remarks for FtpWebRequest.Proxy property. |
| xml/System.Net.Sockets/Socket.xml | Restores Socket overview remarks and sync/async usage guidance. |
| xml/System.Net.Http/HttpClientHandler.xml | Restores remarks about HttpClientHandler and .NET Core implementation differences. |
| xml/System.Net.Http/HttpClient.xml | Restores long-form guidance on HttpClient instancing, pooling, transports, and options. |
| xml/System.Linq.Expressions/Expression.xml | Restores method-level remarks for Expression.Add overloads. |
| xml/System.Linq.Expressions/BinaryExpression.xml | Restores overview remarks summarizing binary expression factory methods. |
| xml/System.Collections.ObjectModel/ObservableCollection`1.xml | Restores overview remarks about data binding and XAML usage. |
| xml/System.Collections.ObjectModel/KeyedCollection`2.xml | Restores method remarks for ChangeItemKey. |
| xml/System.Collections.Generic/List`1.xml | Restores long-form List<T> overview + examples and snippet references. |
| xml/System.Collections.Generic/HashSet`1.xml | Restores long-form HashSet<T> overview remarks and set/LINQ comparisons. |
| xml/Microsoft.Win32/Registry.xml | Restores longer Registry overview remarks content. |
| snippets/visualbasic/System.Numerics/Complex/Overview/Project.vbproj | New VB snippet project for Complex overview. |
| snippets/visualbasic/System.Numerics/Complex/Overview/Program.vb | VB entrypoint for Complex overview snippet project. |
| snippets/visualbasic/System.Numerics/Complex/Overview/precision1.vb | VB snippet source for Complex precision examples. |
| snippets/visualbasic/System.Numerics/Complex/Overview/nan1.vb | VB snippet source for Complex NaN/Infinity examples. |
| snippets/visualbasic/System.Numerics/Complex/Overview/customfmt1.vb | VB snippet source for Complex custom formatting example. |
| snippets/visualbasic/System.Numerics/Complex/Overview/create1.vb | VB snippet source for Complex instantiation examples. |
| snippets/visualbasic/System.Numerics/BigInteger/Overview/Project.vbproj | New VB snippet project for BigInteger overview. |
| snippets/visualbasic/System.Numerics/BigInteger/Overview/Mutability_Examples.vb | VB snippet source for BigInteger mutability/perf examples. |
| snippets/visualbasic/System.Numerics/BigInteger/Overview/ByteAndHex_Examples2.vb | VB snippet source for BigInteger hex parsing example. |
| snippets/visualbasic/System.Numerics/BigInteger/Overview/ByteAndHex_Examples.vb | VB snippet source for BigInteger byte/hex roundtrip examples. |
| snippets/visualbasic/System.Numerics/BigInteger/Overview/BigInteger_Examples.vb | VB snippet source for BigInteger instantiation examples. |
| snippets/visualbasic/System.Collections.Generic/List/Overview/source.vb | New VB snippet source for List<T> overview examples. |
| snippets/visualbasic/System.Collections.Generic/List/Overview/Project.vbproj | New VB snippet project for List<T> overview. |
| snippets/visualbasic/System.Collections.Generic/List/Overview/module1.vb | New VB snippet source for List<T> business-object example. |
| snippets/fsharp/System.Collections.Generic/ListT/Overview/listclass.fs | New F# snippet for List<T> basics (ResizeArray). |
| snippets/fsharp/System.Collections.Generic/ListT/Overview/addremoveinsert.fs | New F# snippet for add/remove/insert example. |
| snippets/csharp/System.Numerics/Complex/Overview/Project.csproj | New C# snippet project for Complex overview. |
| snippets/csharp/System.Numerics/Complex/Overview/Program.cs | C# entrypoint for Complex overview snippet project. |
| snippets/csharp/System.Numerics/Complex/Overview/precision1.cs | C# snippet source for Complex precision examples. |
| snippets/csharp/System.Numerics/Complex/Overview/nan1.cs | C# snippet source for Complex NaN/Infinity examples. |
| snippets/csharp/System.Numerics/Complex/Overview/customfmt1.cs | C# snippet source for Complex custom formatting example. |
| snippets/csharp/System.Numerics/Complex/Overview/create1.cs | C# snippet source for Complex instantiation examples. |
| snippets/csharp/System.Numerics/BigInteger/Overview/Project.csproj | New C# snippet project for BigInteger overview. |
| snippets/csharp/System.Numerics/BigInteger/Overview/Mutability_Examples.cs | C# snippet source for BigInteger mutability/perf examples. |
| snippets/csharp/System.Numerics/BigInteger/Overview/ByteAndHex_Examples2.cs | C# snippet source for BigInteger hex parsing example. |
| snippets/csharp/System.Numerics/BigInteger/Overview/ByteAndHex_Examples.cs | C# snippet source for BigInteger byte/hex roundtrip examples. |
| snippets/csharp/System.Numerics/BigInteger/Overview/BigInteger_Examples.cs | C# snippet source for BigInteger instantiation examples. |
Comments suppressed due to low confidence (1)
snippets/csharp/System.Numerics/Complex/Overview/precision1.cs:36
- These trailing comments are redundant (they restate code already shown) and contain a grammatical error ("where as") plus an incomplete IA64 sentence. Removing them avoids confusion.
// Complex minusOne = new Complex(-1,0);
// Complex.Sqrt(minusOne) returns Complex(6.12303176911189E-17, 1) where as it returns Complex on IA64.
Contributor
Author
|
Snippets 5000 failures are for missing .fsproj files. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Contributes to #12613.
Also removes .NET Framework remarks.